package com.kexio.auth.spi;

import com.kexio.auth.dto.UserAuthInfo;

/**
 * 用户权限信息提供者SPI
 * 
 * 提供用户完整权限信息的加载接口，支持：
 * 1. 从数据库加载用户基础信息
 * 2. 加载用户角色信息
 * 3. 加载用户权限信息
 * 4. 加载数据权限范围配置
 * 5. 支持多租户权限隔离
 * 
 * 实现类需要：
 * - 集成用户管理模块的服务层
 * - 处理权限信息缓存策略
 * - 提供异常处理和降级机制
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
public interface UserAuthInfoProvider {
    
    /**
     * 加载用户完整权限信息
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     * @return 用户权限信息，如果用户不存在返回null
     */
    UserAuthInfo loadUserAuthInfo(String tenantId, String userId);
    
    /**
     * 批量加载用户权限信息
     * 
     * @param tenantId 租户ID
     * @param userIds 用户ID列表
     * @return 用户权限信息映射表，key为用户ID
     */
    java.util.Map<String, UserAuthInfo> loadUserAuthInfoBatch(String tenantId, java.util.List<String> userIds);
    
    /**
     * 刷新用户权限信息（清除缓存并重新加载）
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     * @return 刷新后的用户权限信息
     */
    UserAuthInfo refreshUserAuthInfo(String tenantId, String userId);
    
    /**
     * 检查用户是否存在且状态有效
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     * @return 用户是否有效
     */
    boolean isUserValid(String tenantId, String userId);
    
    /**
     * 获取用户权限版本号
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     * @return 权限版本号，用于缓存版本控制
     */
    Long getUserPermissionVersion(String tenantId, String userId);
    
    /**
     * 预加载用户权限信息到缓存
     * 
     * @param tenantId 租户ID
     * @param userIds 需要预加载的用户ID列表
     */
    default void preloadUserAuthInfo(String tenantId, java.util.List<String> userIds) {
        // 默认实现为空，由具体实现类决定是否需要预加载
    }
    
    /**
     * 获取活跃用户列表（用于权限预加载）
     * 
     * @param limit 返回的用户数量限制
     * @return 最近活跃的用户信息列表
     */
    default java.util.List<UserAuthInfo> getActiveUsers(int limit) {
        // 默认返回空列表，实现类可以根据实际情况提供活跃用户
        return java.util.List.of();
    }
    
    /**
     * 根据角色获取用户列表（用于权限预加载）
     * 
     * @param roleCodes 角色代码数组
     * @return 具有指定角色的用户信息列表
     */
    default java.util.List<UserAuthInfo> getUsersByRole(String... roleCodes) {
        // 默认返回空列表，实现类可以根据实际情况提供角色用户
        return java.util.List.of();
    }
    
    /**
     * 获取权限热点统计（用于优化预加载策略）
     * 
     * @param tenantId 租户ID
     * @param limit 返回的权限数量限制
     * @return 使用频率最高的权限列表
     */
    default java.util.List<String> getHotPermissions(String tenantId, int limit) {
        // 默认返回空列表，实现类可以根据实际使用统计提供热点权限
        return java.util.List.of();
    }
    
}